% -----------------------------------------------------------------------------
%
% Copyright (c) 2017 Sam Cox, Roberto Sommariva
%
% This file is part of the AtChem2 software package.
%
% This file is covered by the MIT license which can be found in the file
% LICENSE.md at the top level of the AtChem2 distribution.
%
% -----------------------------------------------------------------------------

\chapter{Model Installation} \label{ch:installation}

% -------------------------------------------------------------------- %
\section{Requirements} \label{sec:requirements}

AtChem2 can be installed on Linux/Unix and macOS operating systems. A
working knowledge of the \textbf{unix shell} and its
\href{https://swcarpentry.github.io/shell-novice/reference/}{basic commands}
is \emph{required} to install and use the model. AtChem2 requires the
following tools:

\begin{itemize}
\item Fortran -- the model compiles with GNU \texttt{gfortran}
  (version 4.8 and above) and with Intel \texttt{ifort} (version 17.0)\\
  $\hookrightarrow$ default compiler: \texttt{gfortran}
\item Python~\footnote{All Python scripts used in AtChem2 work equally
  with Python v2 and v3. Support for Python v2 will be removed in
  future versions of AtChem2.}
\item make, cmake
\item Ruby (optional)
\end{itemize}

Some or all of these tools may already be present on your operating
system. Use the \texttt{which} command to find out (e.g.,
\verb|which python|, \verb|which cmake|, etc\ldots); otherwise, check
the local documentation or ask the system administrator. In addition,
AtChem2 has the following dependencies:

\begin{itemize}
\item BLAS, LAPACK
\item CVODE
\item openlibm
\item numdiff (optional)
\item FRUIT (optional)
\end{itemize}

For detailed instructions on the installation and configuration of the
dependencies go to Sect.~\ref{sec:dependencies}.

% -------------------------------------------------------------------- %
\section{Download} \label{sec:download}

Two versions of AtChem2 are available for download: the
\href{https://github.com/AtChem/AtChem2/releases/}{stable version} and
the development version, also known as \texttt{master\ branch} (see
Sect.~\ref{sec:general-information} for details). The source code can
be obtained in two ways:

\begin{itemize}
\item with \textbf{git} (This method will download the development
  version and it is recommended if you want to contribute to the model
  development):
  \begin{enumerate}
  \item Open the terminal. Move to the directory where you want to
    install AtChem2.
  \item Execute:
    \begin{itemize}
      \item if using HTTPS:\\
        \verb|git clone https://github.com/AtChem/AtChem2.git|
      \item if using SSH:\\
        \verb|git clone git@github.com:AtChem/AtChem2.git|
    \end{itemize}
  \end{enumerate}
\item with the \textbf{archive file}:
  \begin{enumerate}
  \item Download the archive file (\texttt{.tar.gz} or \texttt{.zip}) of the
    \href{https://github.com/AtChem/AtChem2/releases/}{stable} or of the
    \href{https://github.com/AtChem/AtChem2/archive/master.zip}{development}
    version to the directory where you want to install AtChem2.
  \item Open the terminal. Move to the directory where the archive
    file was downloaded.
  \item Execute \verb|tar -zxfv *.tar.gz| or \verb|unzip -v *.zip|
    (depending on which archive file was downloaded) to unpack the
    archive file.
  \end{enumerate}
\end{itemize}

The AtChem2 source code is now in a directory called \texttt{AtChem2}
(if git was used) or \texttt{AtChem2-1.x} (if the stable version was
downloaded) or \texttt{AtChem2-master} (if the development version was
downloaded). This directory, which can be given any name, is the
\maindir\ of the model. In this manual, the \maindir\ is assumed to
be: \texttt{\$HOME/AtChem2}.

% -------------------------------------------------------------------- %
\section{Dependencies} \label{sec:dependencies}

AtChem2 has a number of dependencies (external tools and libraries):
some are required, and without them the model cannot be installed or
used, others are optional. It is recommended to use the same directory
for all the dependencies of AtChem2: the \depdir\ can be located
anywhere and given any name. In this manual, the \depdir\ is
assumed to be: \texttt{\$HOME/atchem-lib/}.

Before installing the dependencies, make sure that a Fortran compiler
(e.g., \texttt{gfortran}), Python, make, cmake and (optionally) Ruby
are installed on the operating system, as explained in
Sect.~\ref{sec:requirements}.

\subsection{Required dependencies} \label{subsec:required-dependencies}

\subsubsection{BLAS and LAPACK}

BLAS and LAPACK are standard Fortran libraries for linear
algebra. They are needed to install and compile the CVODE library --
see below. Usually they are located in the \texttt{/usr/lib/}
directory (e.g., \texttt{/usr/lib/libblas/} and
\texttt{/usr/lib/lapack/}). The location may be different, especially
if you are using a High Performance Computing (HPC) system: check the
local documentation or ask the system administrator.

\subsubsection{CVODE}

AtChem2 uses the CVODE library which is part of the open source
\href{https://computation.llnl.gov/projects/sundials/}{SUNDIALS suite}
\citep{hindmarsh_2005}, to solve the system of ordinary differential
equations (ODE). The version of CVODE currently used in AtChem2 is
v2.9.0 (part of SUNDIALS v2.7.0) and it can be installed using the
\texttt{install\_cvode.sh} script in the \texttt{tools/install/}
directory.

\begin{enumerate}
\item Open the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2|).
\item Open the installation script (\texttt{tools/install/install\_cvode.sh})
  with a text editor:
  \begin{itemize}
  \item If LAPACK and BLAS are not in the default location (see
    above), change the \texttt{LAPACK\_LIBS} variable for your
    architecture (Linux or macOS) as appropriate.
  \item If you are not using the \texttt{gcc} compiler
    (\texttt{gfortran}), change the line
    \texttt{-DCMAKE\_C\_COMPILER:FILEPATH=gcc \textbackslash}
    accordingly.
  \end{itemize}
\item Run the installation script (change the path to the \depdir\ as
  needed):
  \begin{verbatim}
  ./tools/install/install_cvode.sh ~/atchem-lib/
  \end{verbatim}
\end{enumerate}

If the installation is successful, there should be a working CVODE
installation at \texttt{\textasciitilde/atchem-lib/cvode/}. Take note
of the path to the CVODE library
(\texttt{\textasciitilde/atchem-lib/cvode/lib/}), as it will be needed
later to complete the configuration of AtChem2 (Sect.~\ref{sec:install}).

\subsubsection{openlibm}

openlibm is a \href{https://openlibm.org/}{portable version} of the
open source \textbf{libm} library. Installing openlibm and linking
against it allows reproducible results by ensuring the same
implementation of several mathematical functions across platforms.

The current version of openlibm is 0.4.1 and it can be installed using
the \texttt{install\_openlibm.sh} script in the \texttt{tools/install/}
directory.

\begin{enumerate}
\item Open the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2|).
\item Run the installation script (change the path to the \depdir\ as
  needed):
  \begin{verbatim}
  ./tools/install/install_openlibm.sh ~/atchem-lib/
  \end{verbatim}
\end{enumerate}

If the installation is successful, there should be a working openlibm
installation at \texttt{\textasciitilde/atchem-lib/openlibm-0.4.1/}.
Take note of the path to openlibm, as it will be needed later to
complete the configuration of AtChem2 (Sect.~\ref{sec:install}).

\subsection{Optional dependencies} \label{subsec:optional-dependencies}

\subsubsection{numdiff}

numdiff is an open source \href{https://www.nongnu.org/numdiff/}{tool}
used to compare files containing numerical fields. It is needed only
if you want to run the \hyperref[sec:test-suite]{Test Suite}, a series
of tests used to ensure that the model works properly and that changes
to the code do not result in unintended behaviour. Installation of
numdiff is recommended if you want to contribute to the development of
AtChem2.

Use \verb|which numdiff| to check if the program is already installed
on your system. If not, ask the system administrator. Alternatively,
numdiff can be installed locally (e.g., in the \depdir) using the
script \texttt{install\_numdiff.sh} in the \texttt{tools/install/}
directory.

\begin{enumerate}
\item Open the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2|).
\item Run the installation script (change the path to the \depdir\ as
  needed):
  \begin{verbatim}
  ./tools/install/install_numdiff.sh ~/atchem-lib/
  \end{verbatim}
\item Move to the \texttt{\$HOME} directory (\texttt{cd\ \textasciitilde}).
  Open the \texttt{.bash\_profile} file (or the \texttt{.profile}
  file, depending on your configuration) with a text editor. Add the
  following line to the bottom of the file (change the path to the
  \depdir\ as needed):
  \begin{verbatim}
  export PATH=$PATH:$HOME/atchem-lib/numdiff/bin
  \end{verbatim}
\item Close the terminal.
\item Reopen the terminal. Execute \verb|which numdiff| to check that
  the program has been installed correctly.
\end{enumerate}

\subsubsection{FRUIT}

FRUIT (FORTRAN Unit Test Framework) is a
\href{https://en.wikipedia.org/wiki/Unit_testing}{unit test framework}
for Fortran. It requires Ruby and it is needed only if you want to run
the unit tests (Sect.~\ref{sec:test-suite}). Installation of FRUIT is
recommended if you want to contribute to the development of AtChem2.

The current version of FRUIT is 3.4.3 and it can be installed using
the \texttt{install\_fruit.sh} script in the \texttt{tools/install/}
directory.

\begin{enumerate}
\item Open the terminal. Move to the \texttt{\$HOME} directory
  (\texttt{cd\ \textasciitilde}). Open the \texttt{.bash\_profile}
  file (or the \texttt{.profile} file, depending on your
  configuration) with a text editor. Add the following lines to the
  bottom of the file:
  \begin{verbatim}
  export GEM_HOME=$HOME/.gem
  export PATH=$PATH:$GEM_HOME/bin
  \end{verbatim}
\item Close the terminal.
\item Reopen the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2|).
\item Run the installation script (change the path to the \depdir\ as
  needed):
  \begin{verbatim}
  ./tools/install/install_fruit.sh ~/atchem-lib/
  \end{verbatim}
\end{enumerate}

If the installation is successful, there should be a working FRUIT
installation at \texttt{\textasciitilde/atchem-lib/fruit\_3.4.3/}.
Take note of the path to FRUIT, as it will be needed later to complete
the configuration of AtChem2 (Sect.~\ref{sec:install}).


% -------------------------------------------------------------------- %
\section{Install} \label{sec:install}

To install AtChem2:

\begin{enumerate}
\item Open the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2|).
  Install the \hyperref[sec:dependencies]{Dependencies} and take note
  of the names and paths of CVODE, openlibm and FRUIT.
\item Copy the example \texttt{Makefile} from the
  \texttt{tools/install/} directory to the \maindir:
  \begin{verbatim}
  cp ./tools/install/Makefile.skel ./Makefile
  \end{verbatim}
\item Open the \texttt{Makefile} with a text editor. Set the variables
  \texttt{\$CVODELIB}, \texttt{\$OPENLIBMDIR}, \texttt{\$FRUITDIR} to
  the paths of CVODE, openlibm and FRUIT, as indicated in
  Sect.~\ref{subsec:required-dependencies}. Use full paths, because
  using relative paths may cause compilation errors~\footnote{See
    issue \href{https://github.com/AtChem/AtChem2/issues/364}{\#364}.}.
  For example (change the path to the \depdir\ as needed):
  \begin{verbatim}
  CVODELIB = $(HOME)/atchem-lib/cvode/lib
  OPENLIBMDIR = $(HOME)/atchem-lib/openlibm-0.4.1
  FRUITDIR = $(HOME)/atchem-lib/fruit_3.4.3
  \end{verbatim}
  If FRUIT has not been installed (it is optional), leave the default
  value for \texttt{\$FRUITDIR}.
\item Compile AtChem2 with the \texttt{build\_atchem2.sh} script in
  the \texttt{build/} directory:
  \begin{verbatim}
  ./build/build_atchem2.sh ./mcm/mechanism_test.fac
  \end{verbatim}
  This command compiles the model and creates an executable (called
  \texttt{atchem2}) using the example mechanism file
  \texttt{mechanism\_test.fac} included in the \texttt{mcm/}
  directory.
\item Execute \verb|./atchem2| from the \maindir. This command runs
  the model executable using the default configuration. If the model
  run completes successfully, the following message (or similar) will
  be printed to the terminal:
  \begin{verbatim}
  ------------------
   Final statistics
  ------------------
   No. steps = 546   No. f-s = 584   No. J-s = 912   No. LU-s = 56
   No. nonlinear iterations = 581
   No. nonlinear convergence failures = 0
   No. error test failures = 4

   Runtime = 0
   Deallocating memory.
  \end{verbatim}
\end{enumerate}

When AtChem2 is run for the first time on a macOS system, it may abort
with an error message concerning \texttt{rpath}: if this happens, see
the \textbf{Note for macOS users} on the
\href{https://github.com/AtChem/AtChem2/wiki/How-to-install-AtChem2}{wiki}
for a solution.

AtChem2 is now ready to be used. Optionally, the Test Suite can be run
to check that the model has been installed correctly: go to
Sect.~\ref{subsec:tests-optional} for more information. The directory
structure and the organization of AtChem2 are described in
Sect.~\ref{sec:model-structure} (see also Fig.~\ref{fig:atchem-arch}).
For detailed instructions on how to set up, configure, build and
execute an AtChem2 box-model go to Chapt.~\ref{ch:setup} and
Chapt.~\ref{ch:execution}.

\subsection{Tests (optional)} \label{subsec:tests-optional}

The \hyperref[sec:test-suite]{Test Suite} can be used to verify that
AtChem2 has been installed correctly and works as intended. It is
recommended to run the Test Suite if you want to contribute to the
development of the AtChem2 model. Note that in order to run the Test
Suite the \hyperref[subsec:optional-dependencies]{optional dependencies}
have to be installed.

To run the Test Suite, open the terminal and execute one of the
following commands from the \maindir:

\begin{itemize}
\item \verb|make alltests|: runs all the tests (requires numdiff and
  FRUIT).
\item \verb|make tests|: runs only the build and behaviour tests
  (requires numdiff).
\item \verb|make unittests|: runs only the unit tests (requires
  FRUIT).
\end{itemize}

The command runs the requested tests, then prints the tests output and
a summary of the results to the terminal.

% -------------------------------------------------------------------- %
\section{Model Structure} \label{sec:model-structure}

AtChem2 is organized in several directories which contain the source
code, the compilation files, the chemical mechanism, the model
configuration and output, several scripts and utilities, and the Test
Suite.

The directory structure of AtChem2 is derived from the directory
structure of AtChem-online, but it was substantially changed with the
release of version 1.1 (November 2018). Tab.~\ref{tab:atchem-dirs}
shows the new directory structure and, for reference, the original
one.

\begin{table}[htb]
  \centering \scriptsize
  \caption{Directory structure of AtChem2.\\
    $(\dag)$ Not present in AtChem-online\\
    $(\ddag)$ Called \texttt{travis/} in versions 1.1.* and 1.2.*}
  \label{tab:atchem-dirs}
  \begin{tabular}{llp{3.7cm}}
    Version 1.0 and earlier & Version 1.1 and later & Description\\
    \hline
    --                               & \texttt{build/}                         & scripts to build the model.\\
    \hline
    --                               & \texttt{doc/}                           & user manual and other documents.\\
    \hline
    --                               & \texttt{mcm/}                           & MCM data files and example \texttt{.fac} files.\\
    \hline
    \texttt{modelConfiguration/}     & \texttt{model/configuration/}           & chemical mechanism files, shared library, model and solver configuration files.\\
    \hline
    \texttt{speciesConstraints/}     & \texttt{model/constraints/species/}     & model constraints: chemical species.\\
    \hline
    \texttt{environmentConstraints/} & \texttt{model/constraints/environment/} & model constraints: environment variables.\\
    \hline
    \texttt{environmentConstraints/} & \texttt{model/constraints/photolysis/}  & model constraints: photolysis rates.\\
    \hline
    \texttt{modelOutput/}            & \texttt{model/output/}                  & model output: chemical species, environment variables, photolysis rates, production and loss rates, diagnostic information.\\
    \hline
    \texttt{instantaneousRates/}     & \texttt{model/output/reactionRates/}    & model output: reaction rates of every reaction in the chemical mechanism.\\
    \hline
    \texttt{obj/}                    & \texttt{obj/}                           & files generated by the Fortran compiler.\\
    \hline
    \texttt{src/}                    & \texttt{src/}                           & Fortran source files.\\
    \hline
    \texttt{tools/}                  & \texttt{tools/}                         & various scripts and plotting tools.\\
    \hline
    \texttt{travis/}~$(\dag)$        & \texttt{test/}~$(\ddag)$                & scripts and files for the Test Suite.\\
  \end{tabular}
\end{table}

In AtChem2 version 1.1 (and later versions) the directories
\texttt{build/}, \texttt{mcm/}, \texttt{obj/} and \texttt{src/}
contain the build scripts, the MCM data files, the files generated by
the compiler, the source code; the directory
\texttt{test/}~\footnote{Called \texttt{travis/} in version 1.2 and
  earlier.} contains the files and the scripts necessary to run the
\hyperref[sec:test-suite]{Test Suite}.

For the majority of the users, the most important directories are
\texttt{doc/}, which contains the user manual and other documents,
\texttt{tools/}, which contains the installation and plotting scripts
(plus other utilities), and \texttt{model/}, which contains the model
information (configuration, input, output and, usually, the chemical
mechanism). Detailed information on these three directories can be
found in the following sections.

\subsection{The \texttt{doc/} and \texttt{tools/} directories} \label{subsec:doc-tools-directories}

The \texttt{doc/} directory contains the pdf file of the AtChem2 user
manual (this document: \texttt{AtChem2-Manual.pdf}), along with the
corresponding \LaTeX\ files and figures. An electronic copy of the
poster presented at the 2018 Atmospheric Chemical Mechanisms
Conference \citep{sommariva_2018} is also included
(\texttt{AtChem\_poster\_ACM2018.pdf}).

The \texttt{tools/} directory contains the script
(\texttt{version.sh}, used to update the version number of AtChem2 in
each \hyperref[ch:development]{development cycle}), two scripts to
check and correct the Fortran code (\texttt{fix\_style.py} and
\texttt{fix\_indent.py}, see Sect.~\ref{sec:style-guide}), and the
following subdirectories:

\begin{itemize}
\item \texttt{install/}: contains the example \texttt{Makefile}
  (\texttt{Makefile.skel}) and the scripts to install the
  \hyperref[sec:dependencies]{Dependencies}.
\item \texttt{plot/}: contains basic plotting scripts in various
  programming languages.
\end{itemize}

In earlier versions of AtChem2, the \texttt{tools/} directory also
included the build scripts, which have been moved to the
\texttt{build/} directory in AtChem2 version 1.2.

The plotting scripts in \texttt{tools/plot/} are very simple and
produce identical outputs. They are only intended to give the user a
quick overview of the model results for validation and diagnostic
purposes. It is recommended to use a proper data analysis software
package (e.g., IDL, Igor, MATLAB, Origin, R, etc\ldots) to process and
analyze the model results.

The plotting scripts are written in different programming languages:
gnuplot, Octave~\footnote{GNU Octave is an open source implementation
  of MATLAB. The script \texttt{plot-atchem2.m} works with both Octave
  and MATLAB.}, Python, and R. One or more of these environments is
probably already installed on your system: check the local
documentation or ask the system administrator. All plotting scripts
require one argument -- the directory containing the model output --
and produce the same output~\footnote{See issue
  \href{https://github.com/AtChem/AtChem2/issues/269}{\#269} for a
  list of known problems of the plotting scripts.}: one file called
\texttt{atchem2\_output.pdf} in the given directory.

To run a plotting script, open the terminal and execute one of the
following commands from the \maindir\ (change the path to the model
output directory as needed):

\begin{itemize}
\item \verb|gnuplot -c tools/plot/plot-atchem2.gp model/output/|
\item \verb|octave tools/plot/plot-atchem2.m model/output/|
\item \verb|python tools/plot/plot-atchem2-numpy.py model/output/|
\item \verb|python tools/plot/plot-atchem2-pandas.py model/output/|
\item \verb|Rscript --vanilla tools/plot/plot-atchem2.r model/output/|
\end{itemize}

\subsection{The \texttt{model/} directory} \label{subsec:model-directory}

The \texttt{model/} directory is the most important from the point of
view of the user: it includes the model configuration files, the model
constraints and the model output. Basically, all the information
required to set up and run a box-model with AtChem2, together with the
model results, is contained in this directory. In principle, the
chemical mechanism (\texttt{.fac} file) could be located in another
directory but it is good practice to keep it together with the rest of
the model configuration.

The \texttt{model/} directory can be given any name and can even be
located outside the \maindir. Moreover, there can be multiple
\texttt{model/} directories (with different names) in the same
location. The paths to the required \texttt{model/} directory and/or
to the chemical mechanism file are given as an argument to the build
script (\texttt{build/build\_atchem2.sh}) and to the \texttt{atchem2}
executable, as explained in Sect.~\ref{sec:build} and in
Sect.~\ref{sec:execute}.

This approach gives the user the flexibility to run different versions
of the same model (in terms of configuration and/or chemical
mechanism) or different models (e.g., for separate projects) at the
same time, without having to recompile the source code and create a
different executable every time. Sensitivity studies and batch model
runs are therefore easy to do, since all the parts of the model that
have to be modified are contained in the same directory. Further
information can be found in Sect.~\ref{subsec:build-process}.\\

\textbf{Important Note}: whenever the \texttt{model/} directory is
mentioned in this manual, it is implied that its name and location may
be different than the default name (\texttt{model/}) and location
(\maindir). All scripts that require this information, as well as the
\texttt{atchem2} executable, allow the user to specify the path to the
\texttt{model/} directory and to its subdirectories, as needed.
